/**
 * 权限装饰器
 * 用于控制接口的访问权限
 * 配合 PermissionAuthGuard 使用
 */
import { SetMetadata } from '@nestjs/common';
import { PERMISSION_KEY } from '../constants/decorator.constant';

/**
 * 权限数据接口
 * @property permissions - 权限列表
 * @property strategy - 权限验证策略
 */
export interface PermissionData {
  permissions: string[];
  strategy: PermissionStrategyEnum;
}

/**
 * 权限验证策略枚举
 * OR: 满足其中一个权限即可访问
 * AND: 必须满足所有权限才能访问
 *
 * 使用示例：
 * 1. OR策略（默认）
 *    @Permission(['user:create', 'user:admin'])
 *    // 拥有 user:create 或 user:admin 任一权限即可访问
 *
 * 2. AND策略
 *    @Permission(['user:create', 'department:manage'], PermissionStrategyEnum.AND)
 *    // 必须同时拥有 user:create 和 department:manage 权限
 */
export enum PermissionStrategyEnum {
  OR = 1, // 或运算：满足其中一个权限即可
  AND = 2 // 与运算：必须满足所有权限
}

/**
 * 权限装饰器
 * @param permissions - 单个权限字符串或权限字符串数组
 * @param strategy - 权限验证策略，默认为 OR
 *
 * 使用示例：
 * 1. 单个权限
 *    @Permission('user:list')
 *
 * 2. 多个权限（OR）
 *    @Permission(['user:create', 'user:admin'])
 *
 * 3. 多个权限（AND）
 *    @Permission(['role:update', 'role:admin'], PermissionStrategyEnum.AND)
 */
export const Permission = (
  permissions: string | string[],
  strategy = PermissionStrategyEnum.OR
) => {
  const permissionData: PermissionData = {
    permissions: [],
    strategy
  };

  // 处理单个权限
  if (typeof permissions === 'string') {
    permissionData.permissions = [permissions];
  }
  // 处理多个权限
  else if (Array.isArray(permissions)) {
    permissionData.permissions = permissions;
  }

  // 设置元数据，供 PermissionAuthGuard 使用
  return SetMetadata(PERMISSION_KEY, permissionData);
};
